Tech Arsenal 1/Tech Arsenal (Arsenal Computer).ISO/tek-02/powrdoor.zip/POWRDOOR.DOC

Text File | 1991-09-26 | 16KB | 360 lines

       PowerBBS's PowerDOOR - A Programmers Door Interface to PowerBBS

               (c) 1991 by Russell E. Frey; All Rights Reserved

                                35 Fox Ct.
                            Hicksville, NY 11801

                          Support Line [phone]

To use PowerDOOR, you will need a copy of Turbo Pascal for Windows (tm).

No code produced with PowerDOOR may be sold commercially.  You may produce
doors for your own use, or issue the doors into public domain or shareware.
If you want to produce commercial code, then please contact Russell Frey,
for a prior contract and licensing agreement.

Doors produced under the SHAREWARE concept may be distributed, so long
as there are no limitations to the registered version (and must be
shareware as according to the Association of Shareware Professionals).
The registered version should be the same program, with the exception
of a Registered to: line, instead of not-registered.

To produce a door with PowerDOOR, the following requirements are held:

 1) You must place powrwin and powrdoor in your uses
    statement.

 2) You must always begin your program with (begin_live_program(name);) and
    end your program with (end_live_program;)

An example program, blackjack, is included in this package (black.pas).  As
with any PowerBBS Live Program, to set up the live door, you will place the
following in your live.dat:

c:\wsource\black.exe c:\powrbbs\powrwin.dat,10,

All windows live programs must contain the .exe, and path to the data file.

A Copy of PowrSYS.PAS is now incuded!  Use to modify, or just to learn
about how PowrDOOR works!

If you write a door, or code that you would like to distribute, please
upload your programs to the support bbs [phone].  The existence
of programs using PowerDoor, will give me an incentive to continue
supporting the programming community.

Feel free to upload modifications to the sample source code to our
bbs.

The following procedures/functions/structures are currently available for
your use:

--> procedure begin_live_program(name_of_prog: string);
Use to open PowerDOOR.  Name of Prog variable, is the name of your program.

--> procedure end_live_program;
Needed to close PowerDoor.

--> procedure write_com(msg: string);
Writes a string to the user.  If user is remote, information is sent
to the com port, etc.

--> procedure writeln_com(msg: string);
Same as write_com, except a return is entered at the end of output.

--> procedure writelncom;
This procedure will return a blank return to the screen.  You could
do the same thing with writeln_com('');

--> procedure writeln_com_spaces(numberof: integer);
Sends the specified number of spaces to the com port.

--> procedure writeln_com_border(beginx,width_border: integer);
Displays a border (|------------|), starting at the x coordinate
with the given width specified.

--> procedure writeln_com_node_status;
Writes the node status screen, with the current callers on-line the
different nodes.

--> function infotext(pline: string): string;
Will interpret |MACROS|.  For example, you can do:
writeln_com(infotext('Welcome |NAME|'));

--> function drop_carrier: boolean;
If user is not online, then this function is set to TRUE.  You should always
use this in any loop structure, such as:
 Repeat
  delay(50);
 Until (drop_carrier) or (your statements);

--> procedure get_a_return;
Tells the user to press return (or enter), and will wait till it is pressed.

--> procedure activity(stringtowrite: string);
Writes the information to the activity_log file.

--> procedure clearscreen;
Clears the screen, including the users screen, if ANSI is turned on.

--> procedure type_file(file: string);
Types a file to the user. If you use type_file('wel'), then the file
wel, will be displayed.  If welc is available, and the user has ANSI
capability, then it will be displayed.  (Notice c for color)

--> function user_abort: boolean;
If this function returns TRUE, the user wants to abort.  This function
displays ::Pause:: [S]top, etc.  Use this in the middle of a procedure
which outputs lots of text, that you want the user to be able to abort.
Example:
                Repeat
                  inc(counter);
                  writeln_text(info[counter]);
                  if user_abort then exit;
                Until (counter = 100) or (drop_carrier);

--> procedure ask_user(input_string: string;
                   max_input_length: integer);
This procedure should be used to get input from the user, such as a
Readln(string), statement.  Notice that max_input_length, is the
maximum length the string input is permitted to be.

--> function input_char: char;
This function will receive one character from the user.

--> procedure Get_Hotkey(Var Char_Get: Char);
Waits till one character is available, and will return the first carrier
into Char_Get.  Will also return, if carrier drops, etc.

--> function get_hotkey_yn: boolean;
This procedure will wait until the keys y or n are pressed.  It will display
Yes or No, and a return after the key has been pressed.
get_hotkey_yn is TRUE if yes is pressed.

--> Procedure Get_Date(Var NewDate: String;
                          OK_Default: Boolean;
                          Default: String);
Will ask the user for a date.  If OK_DEFAULT is set to Yes, then when
the user selects only ENTER, the Default will be returned.  Otherwise,
the new date will be entered into NewDate.

--> Function GetInput(One_Key: Boolean;
                   Var Answer: String;
                       Max_An: integer): Boolean;
Gets an input from user.  Default [ENTER=Quit].  If Enter is selected,
TRUE is returned.  Otherwise FALSE is returned, with Answer the resulted
input.  Max_An is maximum input size (set to one when One_Key is selected).

--> Procedure Get_A_Input(     Format: String;
                          Var NewDate: String;
                           OK_Default: Boolean;
                              Default: String);
This is a more complicated input.  It is used for number type inputs,
(dates, phone numbers, etc).  Format is the format of input (###-###-####,
##/##/##, etc).  NewDate is where the input will be sent to.  If Ok_Default
is selected, then when the user presses the Enter key, Default will be
sent to NewDate.

--> procedure save_userinfo;
This program will save the USERINFO record.  Use this only if you want
to save updated information.

--> function search_userrec_for(var searchfor: PowrUser; name: char25): integer;
Searches for the given NAME in user record file. If not found, 0 is returned,
otherwise record number is returned.

--> function ljust(source: string; num: integer): string;
    function rjust(source: string; num: integer): string;
Adjusts a string according to the NUM.

--> procedure put_chars_into(var sendto;
                             from:  string;
                             total_bytes_to_move: integer);
Moves characters from the from string to the sendto pointer.  This
is useful for char packed array types.

--> function asc_to_int(temps: string): integer;
Converts an ascii string to an integer

--> function int_to_asc(tempint: integer): string;
Converts an integer to a string

--> function double_to_kilobyte(fromd: double): string;
Converts a double type to a kilobyte string.

--> procedure real_to_double(fromr: real;
                             var tod: double);
Converts reals to doubles.

--> procedure upper_string(var tempstring: string);
Converts all letters to capital in a string

--> procedure delete_after_spaces(var tempstring: string);
Removes any spaces at the end of a string

--> procedure delete_before_spaces(var tempstring: string);
Removes any spaces at the beginning of a string

--> function bit_from_byte(from: byte; bit_value: byte): boolean;
Returns the current bit value

--> procedure set_bit_byte(var from: byte; bit_value: byte; to_set_to:boolean);
Sets the specified bit value to to_set_to.

--> procedure delay(time_ms: longint);
Delays and yields control, for the specified milliseconds.
Delay(1000) = delay and yield control for 1 full second.
You should enter this if you have a repeat -- until, to yeild control
to other applications.

--> function SENDRED:     string;  Sends ANSI foreground RED
--> function SENDGREEN:   string;  Sends ANSI foreground GREEN
--> function SENDYELLOW:  string;  Sends ANSI foreground YELLOW
--> function SENDBLUE:    string;  Sends ANSI foreground BLUE
--> function SENDMAGENTA: string;  Sends ANSI foreground MAGENTA
--> function SENDCYAN:    string;  Sends ANSI foreground CYAN
--> function SENDWHITE:   string;  Sends ANSI foreground WHITE
--> function SENDGRAY:    string;  Sends ANSI foreground GRAY
--> function SENDBrown:   string;  Sends ANSI foreground BROWN
--> function SENDBLUEBACK:string;  Sends ANSI background BLUE
--> function SENDRedback: string;  Sends ANSI background RED
--> function SENDPUPback: string;  Sends ANSI background PURPLE

File I/O Routines in PowerDOOR

var
 file_handle: integer;  (* Given File Handle by operating system *)

--> function open_file(name: string;
                       open_method: integer): file_handle;
Opens a file.
Method integer should be either 0,1, or 2, where:
0 = Open to read a file
1 = Open to write a file
2 = Open to read and write a file
Example: AUTO_Handle := Open_file('C:\Autoexec.bat',2);

--> function read_file(the_handle: file_handle;
                       var buffer;
                       number_bytes: word): word;
Reads from an opened file.
Returns the number of bytes actually read.
Example: Bytes_Read := Read_File(AUTO_Handle,receive,10);

--> function write_file(the_handle: file_handle;
                        var buffer;
                        number_bytes: word): word;
Writes to an opened file.
Returns the number of bytes actually written.
Example: Bytes_Written := Write_File(AUTO_Handle,'Write This',10);

--> function seek_file(the_handle: file_handle;
                       seek_to:    longint;
                       seek_type:  integer): longint;
Seeks to the specified position in a file.  It calls the Windows API
(you could actually use the API directly).
Seek_type: 0 - Seek from start of file
           1 - Seek from current position in file
           2 - Seek from end of file

--> procedure close_file(the_handle: file_handle);
Closes the file.

--> function file_exists(name: string): boolean;
Checks to see if a file exists.  If the file exists, TRUE is returned,
otherwise FALSE is returned.

The following record is available, via the USERINFO. declaration.
For example, USERINFO.NAME would be the current Users Name.

Type Forum_Type = Record
     Options:  Byte;      {Forum Options:
                           Bit0: Access No/Yes
                           Bit1: Scan No/Yes}
     Lastread: Single;    {Last message read pointer}
    End;

Type PowrUser = Record    {Format of the USER database}
       Name:  Packed Array[1..25] Of Char;        {User Name}
       Location:  Packed Array[1..20] Of Char;    {User Location}
       Computer:  Packed Array[1..15] Of Char;    {User Computer Type}
       Phone_Number: Packed Array[1..14] Of Char; {User Phone Number}
       Password:  Packed Array[1..10] Of Char;    {User Password}
       Birthday:  DateType;                       {date of birth}
       First_Call: DateType;                      {date of first logon}
       Last_File_Scan: DateType;                  {date of last NEW scan}
       Expiration_Date: DateType;                 {date subscription ends}
       Last_Call: DateType;                       {date of last logoff}
       Last_Time: TimeType;                       {time of last logoff}
       Calls: Integer;                            {total number of calls}
       Uploads: Integer;                          {number of uploads}
       Downloads: Integer;                        {number of downloads}
       Time_on: Integer;                          {time on today}
       Today_bytes: Double;                       {bytes downloaded today}
       Download_Bytes: Double;                    {bytes downloaded}
       Uploads_Bytes: Double;                     {bytes uploaded}
       Forum_Data:  Array[0..200] Of Forum_Type;
       Access: Byte;                              {access level}
       Expiration_Access: Byte;                   {access after expiration
                                                        date}
       Screen_lines: Byte;                        {number of lines to a screen}
       Safe_Total: Byte;                          {total minutes in safe}
       Options: Byte;                             {options:
                                                    bit0: Expert On/Off
                                                    bit1: Hotkey On/Off
                                                    bit2: Bad User On/Off}
       Xproto: Char;                              {default file xfer protocol}
       Monitor_Type: Char;                        {type of monitor:
                                                    'C' => Color
                                                    'M' => Monochrome
                                                    'N' => None}
       Messages_Left: Word;                       {Number of messages left}
       Reserved: Array[1..200] of byte;
      End;

The following record, can be interfaced by using the CALLINFO record.
For example, the name is CALLINFO.NAME

Type Powr_CallInfo = Record  {Format of Callers Info File For Live Programs}
       Name:  Packed Array[1..25] Of Char;     {User Name}
       User_Pointer: Integer;                  {User Record # starting at 1}
       BaudRate: Packed Array[1..5] Of Char;   {Baud rate to send at}
       Scomport: Char;                         {Com Number to send at}
       What_Menu: byte;                        {Current Menu}
       Graphics: Char;                         {Graphics Type:
                                                 'C' => Color
                                                 'M' => Monochrome
                                                 'N' => None}
       Access: Byte;                           {User Access Level}
       ForumNum: Byte;                         {Current Forum Number}
       Logon_Time: TimeType;                   {time of logon}
       Logon_Mins: Integer;                    {time the user logged on in mins}
       Used_today: integer;                    {time the user used in
                                                previous calls so far today}
       Time_Limit: integer;                    {Maximum mins permitted on bbs}
       Kdownload_Maximum: Integer;             {Maximum download bytes in K}
       Upload_Credit: Integer;                 {Minutes given for Uploading}
       Minutes_Useable: Integer;               {Maximum Time left for caller}
       Node_Num: Byte;                  {The node number of this callinfo file}
       Path_Data: string[30];           {path to powrwin.dat}
       Reserved1: Array[1..2] Of Char;
       Reserved2: Byte;
       Reserved3: Longint;
      End;

Reserved
--------

Some of the reserved variables are used internally by PowerBBS, so
DO NOT touch the reserved variables.

Global Variables
----------------

CallerLog --------> Path to the caller activity log file

UserFile_Path ----> Path to the users database file

Max_Forums -------> Maximum number of forums